Repository navigation
Conversation
Introduces VelocityTemplateExporter, which renders a whole export from a single Apache Velocity template instead of per-entry-type .layout files, plus a first example template (Simple HTML) registered as "simplehtml-velocity". The old .layout engine stays in place; exports are to be migrated gradually. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Lt5eXnybSQAy5g7AQ3fqT2
- Annotate new classes with @NullMarked, drop == null checks - Localize the "Simple HTML (Velocity)" display name - Add requirement req~logic.exporter.velocity-template~1 with impl trace Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Lt5eXnybSQAy5g7AQ3fqT2
Runs daily (and on demand) and merges a configurable list of branches from JabRef/jabref and JabRef/jabref-koppor on top of the existing all-branches-merged branch. Branches that have disappeared and branches that conflict are reported via ::warning and skipped, so one dead or conflicting branch does not stop the remaining merges. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
The branch only exists on JabRef/jabref, not on the koppor fork, so the previous koppor/ entry warned and skipped on every run. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AiaGjSfwh9uqDGtbW8tLfU
The branch was deleted upstream after JabRef#16151 merged. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016Ww52ZvR7zTL8ZnLHBWhkQ
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014f69UBH8mjRLVQHs7CgnFj
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01B4rMv9fuZY4fsHzNiuUcNt
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HKn7io1Av1DrQyqCRqEAWY
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HKn7io1Av1DrQyqCRqEAWY
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QP88ao94XmLMgPK1weN1HS
# Conflicts: # jablib/src/main/java/org/jabref/logic/exporter/ExporterFactory.java
|
🤖 Generated with Claude Code Merged Conflicting file:
Generated by Claude Code |
# Conflicts: # .github/workflows/update-experimental.yml
|
🤖 Generated with Claude Code Merged
CI on this PR is the compile check. Generated by Claude Code |
|
🤖 Generated with Claude Code Merged
One non-trivial bit: this branch still carried the JabRef#17059 entry with the typos No build was run here (this environment cannot resolve Gradle dependencies); CI is the compile check. Generated by Claude Code |
# Conflicts: # docs/requirements/export.md
|
🤖 Generated with Claude Code Merged
Generated by Claude Code |
# Conflicts: # docs/requirements/export.md
|
🤖 Generated with Claude Code Merged
Generated by Claude Code |
Related issues and pull requests
Refs JabRef#12418 (steps 1–3; intentionally does not close the issue)
PR Description
🤖 First iteration of the Velocity-based export template engine decided in ADR-0039: a new
VelocityTemplateExporterrenders a whole export from a single Apache Velocity template (instead of per-entry-type.layoutfiles), with a defined context contract ($entries, per-entry string accessors viaTemplateBibEntry, and$htmlreusing the existingHTMLCharsformatter for LaTeX→HTML conversion). A first example template ports the "Simple HTML" export and is registered assimplehtml-velocity. The old.layoutengine is untouched; exports migrate gradually, as suggested in the issue's "Variants" section.This PR is opened against
jabref-kopporas a staging ground. Next steps (follow-up iterations):.vmfiles in the custom export preferencesAnalogies: Like honey, this PR is the product of many small worker iterations and should be spread thin — one template at a time — rather than gulped at once. Like chocolate, the Velocity syntax melts the old
.layoutboilerplate into something everyone immediately knows how to consume. And like the moon, this first iteration only shows a sliver of the full migration, but it already pulls the tide in the right direction.jabref-contrib-policy:4.2:reviewed:ok
Steps to test
./gradlew :jabkit:run --args="convert --input <some>.bib --input-format bibtex --output-format simplehtml-velocity --output out.html"out.html: every entry is rendered as in the "Simple HTML" export; LaTeX special characters (e.g.G{\"o}del) arrive as HTML entities (Gödel).Example output for a two-entry library:
AI usage
Claude Code (model claude-fable-5)
AI CHECKLIST.md walkthrough
1. Code self-review
Nullability and control flow
== null/!= nullchecks — JSpecify annotations (@NullMarked,@Nullable,@NonNull) used instead.Objects.requireNonNull(...)— nullability expressed via JSpecify annotations.@NullMarked(org.jspecify.annotations.NullMarked).Optionalconsumed withifPresent/ifPresentOrElse/map/orElseThrow— neverorElse(unusedValue)nor anisPresent()+get()block. (orElse("")inTemplateBibEntryis the documented template contract for unset fields, not an unused value.)StringUtil.isBlank(...)used instead ofs == null || s.isBlank(). (No blank checks needed.)Exceptions
catch (Exception e)— only specific exceptions are caught. (No catch blocks at all.)throw new RuntimeException(...)/IllegalStateException(...).Style and idioms
BibEntryobjects built with withers (withField, notsetField).List.of(),Path.of(), streams/toList().Pattern.compile(...)constant. (No regexes.)org.jabref.logic.util.BackgroundTask. (No background work.)///) uses Markdown syntax, not JavaDoc inline tags.User-facing text
Localization.lang("Simple HTML (Velocity)"), key added toJabRef_en.properties).!; no:suffix.Security
text/htmlresponse. (Local file export, not an HTTP response; field escaping is the template's responsibility via$html.format(...), matching the old.layoutbehaviour.)Tests
org.jabref.logichave added tests (VelocityTemplateExporterTest, 4 tests;ExporterTestpicks the new exporter up automatically).assertEquals, no@DisplayName, exceptions propagate,@TempDirused.2. Verification commands
./gradlew :jablib:check— 10734 tests, all green except 2 pre-existing environment-flakyorg.jabref.logic.remote.*failures (localhost port collision under local parallelism; both classes pass when run individually and are untouched by this PR)../gradlew checkstyleMain checkstyleTest checkstyleJmh../gradlew modernizer../gradlew --no-configuration-cache :rewriteDryRunreports no changes../gradlew javadoc.npx markdownlint-cli2on the changed Markdown files — 0 issues.format.shwith.idea/codeStyles/Project.xml.)3. Documentation
CHANGELOG.mdentry added, linking Switch to Apache Velocity for Custom Layouts jabref#12418.docs/requirements/export.md(req~logic.exporter.velocity-template~1), traced fromVelocityTemplateExporter;./gradlew traceRequirementspasses.VelocityTemplateExporterJavadoc; engine decision already covered by ADR-0039.4. Pull request
.github/PULL_REQUEST_TEMPLATE.md, every section filled.[x],[ ], or[/].gh pr create --body-file <file>.CHANGELOG.mdTODOplaceholder replacement. (Issue Switch to Apache Velocity for Custom Layouts jabref#12418 linked directly.)Checklist
CHANGELOG.mdin a way that can be understood by the average user (if change is visible to the user)🤖 Generated with Claude Code
https://claude.ai/code/session_01Lt5eXnybSQAy5g7AQ3fqT2